package com.fwzhang.third.collectionframework.collection.queue;

import java.util.Collection;

public interface QueueInterface<E> extends Collection<E> {

    /**
     * 向队列中增加一个元素
     * 在队列容量已满时，add会抛出IllegalStateException
     * {@link #offer} 在容量已满时不抛出异常，只返回false
     *
     * @param e element whose presence in this collection is to be ensured
     * @return <tt>true</tt> if this collection changed as a result of the
     * call
     * @throws UnsupportedOperationException if the <tt>add</tt> operation
     *                                       is not supported by this collection
     * @throws ClassCastException            if the class of the specified element
     *                                       prevents it from being added to this collection
     * @throws NullPointerException          if the specified element is null and this
     *                                       collection does not permit null elements
     * @throws IllegalArgumentException      if some property of the element
     *                                       prevents it from being added to this collection
     * @throws IllegalStateException         if the element cannot be added at this
     *                                       time due to insertion restrictions
     */
    @Override
    boolean add(E e);

    boolean offer(E e);

    // 删除队列头部元素，并返回

    /**
     *
     * @return E
     * @throws java.util.NoSuchElementException  队列为空时抛出该异常
     */
    E remove();

    /**
     * 队列为空时返回null
     * @return E or null
     */
    E poll();

    // 获取队列头元素

    /**
     *
     * @return E
     * @throws java.util.NoSuchElementException 队列为空时抛出该异常
     */
    E element();

    /**
     * 队列为空时返回null
     * @return E or null
     */
    E peek();
}
